governmentwikiaorg-20200215-history
Help:Template documentation
are a very powerful feature of MediaWiki, but can be confusing to new users, and even experienced users can have difficulty making sense of the more complex ones. Templates should therefore be accompanied by documentation to improve usability. Template documentation should explain what a template does and how to use it. It should be simple enough for correct use by a user without complete knowledge of the intricacies of template syntax – which includes many experienced contributors who focus their attention elsewhere. This is especially true in the case of very widely-used templates. What to include Documentation should cover: * The basic purpose of the template: what it does, and (if it is not immediately obvious) why it needs to be done. If there are other templates with similar names or purposes, it's a good idea to mention those, to reduce the chance of the wrong one being used. * Any parameters that the template takes. Explain whether they are numbered or named, whether they are optional (and if so, what the default value is), and what effect they have. If a parameter can take only a limited set of values ("yes" or "no", for example), must be a number, or is constrained in some other way, this should be made clear. * Usage examples. Specify the exact wikitext that should be used, and the result it produces. The wikitext can be enclosed in ... tags to make it clear and easy to copy, like this. If the template can be used in several different ways (with or without optional parameters, for example), provide a range of examples. A good way to do so is to transclude the template itself into the documentation a few times, with different parameters each time, and list the parameters used in each case. * Related templates. If the template is one of a series of templates, include links to these – in particular, ensure that every template in the series is linked from each of the others, as this makes navigation easier. (A separate navigation template may be useful for this purpose; see for example Template:Protection templates). * Appropriate categories and interwiki links, where applicable. Like the documentation, these must be contained within ... tags. Many template categories are available; go to Category:Wikia templates to browse through them. You may also see the larger number at Wikipedia:Category:Wikipedia templates, most of which can be copied to this wiki in the normal way with template:enWP in the "noinclude" part. Template documentation is often placed in a subpage of the template itself, which is then transcluded at the end of the template page. This separates the often complex template code from the documentation, making the documentation easier to edit. It also allows templates to be protected where necessary, while allowing anyone to edit the documentation. This method is sometimes referred to as the "template doc page pattern". Documentation of any sort on a template page should always be enclosed by ... tags (starting in the same line as previous material), so that it does not show up when the template is used on another page. Text on the template page itself adds to the amount of text that must be processed when displaying the template, which is limited for performance reasons. Placing the documentation in a subpage avoids this (MediaWiki developers have recommended it for this reason). How to create a documentation subpage See project:Template_doc_page_pattern#How_to_do_it. Example See the heavily-used Template:Cite web for an example of detailed template documentation. Note that the template itself is protected, but the documentation subpage, Template:Cite web/doc, is unprotected and can still be edited. See also * Template:template doc page transcluded * Template:template doc page viewed directly External links * and and * Wikipedia:Wikipedia:High-risk templates Category:Template documentation